همواره یکی‌از ایرادات برنامه نویس ها برای به کار گیری از APIها (در اینجا مراد اینترنت خدمات است) مشخص و معلوم نبودن طریق به کارگیری از متدهای ارائه گردیده و به هیچ عنوان کاربرد هرکدام از آن ها است.  طراحی سایت شرکتی اکثر ما تجربه عمل با APIهای پرداخت آنلاین خزانه های مختلفی را داشته ایم. نشانی اینترنت خدمات داده میشود و شما می بایست از خدمت های موردنیاز ارائه گردیده درین نشانی به کارگیری فرمایید، سوای اینکه راهنمای قابل قبولی داشته باشید. بعداز دسترسی به خدمات بایستی به‌دنبال فولدر راهنمای به کار گیری از آنان باشید که هرکدام چه کاری را انجام میدهند و مقادیر ورودی و خروجی آن ها چه‌طور میباشد.(حال این فولدر راهنما برای ورژن پایان ارائه گردیده می‌باشد یا این که برای ورژن های گذشته میباشد.)

برای طرف های ارائه دهنده اینترنت خدمت هم دشواری های متعددی برای گفت و گو مستندسازی و ساخت‌و‌ساز راهنمای بروز برای خدمت های خویش وجود دارااست. آیا برنامه نویس ها فولدر word راهنما را طبق تغییرات کد خویش آپ تو دیت کرده اند یا این که خیر و آیا این ورژن پایان از فولدر راهنما به دست مصرف کنندگان از API رسیده میباشد یا این که نه!؟

همگی این ایرادات سبب ساز گردیده تا ابزاری بسیار کاربردی برای ساخت راهنما به کارگیری از API ساخت‌و‌ساز خواهد شد که دو طرف نیز در استعمال از لذت خواهند موفقیت.

Swagger چه چیزی است ؟
یک ابزار بسیار کارکشته برای ساخت و ساز راهنمای آنلاین و اکران شماتیک API ها (خدمت های پایین اینترنت مخصوصا WebAPI) هست که محبوبیت خیلی متعددی فی مابین یوزرها خویش داشته میباشد به طوریکه برای 25 گویش بسط داده شده‌است. در اینجا میخواهیم شیوه به کار گیری از آن را در ASP.NET Core بر روی dotNET Framework نشان دهیم. از Swagger می‌توانید در ASP.NET MVC نیز براحتی به کارگیری فرمائید(با به کار گیری از نصب nuget Package آن).

برای استارت یک پروژه ASP.NET Core WebApplication بر روی بستر dotNET Framework طبق تصویر ذیل ساخت و ساز می نمائیم.

آن‌گاه در پروژه ساخت‌و‌ساز گردیده و در نصیب SolutionExplorer فولدر priject.json را گشوده کرده و کد پایین را در آن اضافه می نمائیم. با این تغییر تحول package مرتبط با Swagger به پروژه اضافه گردد. (\"Swashbuckle\": \"6.0.0-beta902\"). بعداز اضافه کردن این خط به انتهای پوشه، می بایست تغییرات پوشه را ذخیره (ctrl + s) فرمایید تا package متبوع بر روی پروژه Restore شود.

بعداز مرحله نصب package اکنون برای به کارگیری از package، می بایست آن را در پوشه Startup.cs نیز برای به کار گیری معرفی نمائیم و تغییراتی درین فولدر تولید نمائیم. در صدر بایستی قطعه کد services.AddSwaggerGen را در ConfigureServices طبق تصویر پایین اضافه نمائیم.

1
2
3
4
5
6
7
public void ConfigureServices(IServiceCollection services)
{
// Add framework services.
services.AddApplicationInsightsTelemetry(Configuration);
services.AddMvc();
services.AddSwaggerGen();
}

بعد دو خط پایین را در متد Configure اضافه نمائیم :

1
2
3
4
5
6
7
8
9
10
11
12
public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
{
loggerFactory.AddConsole(Configuration.GetSection(\"Logging\"));
loggerFactory.AddDebug();

app.UseApplicationInsightsRequestTelemetry();
app.UseApplicationInsightsExceptionTelemetry();

app.UseMvc();
app.UseSwagger();
app.UseSwaggerUi();
}

به همین راحتی شما یک مستندساز بی نقص برای WebAPI های خویش به دست آورده اید. درحال حاضر میتوانید پروژه خویش را اجرا فرمائید و در انتهای نشانی در مرورگر عبارت /swagger/ui را برای مشاهده راهنمای خدمت های خویش مشاهده کنید.به طور نشانی تحت :
http://localhost:25239/swagger/ui

نکته : در مرحله آزمایش میتوانید براحتی طبق تصویر پایین نشانی پیش فرض خویش را به نشانی بالا تغییر‌و تحول دهید تا در هر توشه اجرای پروژه کاغذ مربوطه به راهنمای APIها اکران داده خواهد شد.برای اعمال این تغییر‌و تحول بر روی اسم پروژه خویش در Solution Explorer کلیک راست کرده و آیتم Properties را گزینش فرمایید و در بخش Debug تغییر تحول تحت را ساخت فرمائید.

درحال حاضر پروژه خویش را اجرا فرمایید.بایستی مانند تصویر تحت را مشاهده فرمائید. شما هم مطلقا مثل اینجانب که اولی توشه از Swagger به کارگیری نمودم تعجب نمایید که داشتن یک راهنمای گرافیکی و معلوم برای WebAPI چقدر معمولی بود و ما پیش از آن چقدر بر رمز تصحیح کردن راهنما دشواری می کشیدیم. شما در تصویر ذیل به تعداد Controller های api که نوشته باشید یک سطر اضافه می‌گردد که نشان دهنده یک controller می‌باشد که در پی هم متدهای آن controller را مشاهده می نمایید.

حال می‌خواهیم پاره ای توضیحات هم برای ارشادوراهنمایی بهتر بدین کاغذ اضافه نمائیم. در صدر توضیحات درباره با شرکتی که‌این خدمت را ارائه می نماید و چه کسی این را نوشته و داده ها تماس اپ نویس API را در شکل نیاز طبق کدهای ذیل در کلاس Startup اضافه می نمائیم.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
public void ConfigureServices(IServiceCollection services)
{
// Add framework services.
services.AddApplicationInsightsTelemetry(Configuration);
services.AddMvc();
services.AddSwaggerGen();
services.ConfigureSwaggerGen(options =>
{
options.SingleApiVersion(new Info
{
Version = \"v1\",
Title = \"SepidAria API\",
Description = \"My First ASP.NET Core Web API\",
TermsOfService = \"None\",
Contact = new Contact() { Name = \"Mohsen Derambakht\",
Email = \"info@sepidaria.com\", Url = \"www.sepidaria.com\" }
});
});
}

دوباره پروژه خویش را اجرا فرمایید و در بالای ورقه توضیحات گذارده گردیده را مشاهده خواهید کرد.

این هم از توضیح برای کاغذ راهنمای اینترنت خدمت های خویش. در غایت میخواهیم برای هر خط از خدمت های خویش نیز توضیحاتی بیاوریم. توضیحات مانند شرح یک خدمت، خطاهای و پیغام های دریافتی و مورد ها دیگر. میخواهیم از توضیحات summary که بالای هر متد که اکثر برنامه نویسان توضیحاتی می نویسند به کار گیری نمائیم و آنان را در نیز در ورقه راهنما اکران دهیم.

برای این عمل در آغاز به کاغذ Properties پروژه می‌رویم و این توشه بخش Build را گزینش می نمائیم. آن‌گاه طبق تصویر پایین در انتهای برگه آیتم
XML documentation file را تیک میزنیم.

اکنون بایستی دوباره در پوشه Startup.cs تغییراتی را برای قرائت پوشه xml بوسیله Swagger اضافه نمائیم. نخست متد تحت را در پوشه Startup.cs
اضافه کنید.

1
2
3
4
5
private string GetXmlCommentsPath()
{
var app = PlatformServices.Default.Application;
return System.IO.Path.Combine(app.ApplicationBasePath, \"ProjectName.xml\");
}

نکته : لطفا توجه نمائید که در انتهای خط چهارم در کدهای بالا به مکان ProjectName اسم پروژه خویش را که در SolutionExplorer دیده میشود را قرار دهید.

اکنون می بایست متد ConfigureService را در همین پوشه به صورت تحت تغییر تحول دهید:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
public void ConfigureServices(IServiceCollection services)
{
// Add framework services.
services.AddApplicationInsightsTelemetry(Configuration);
var xmlPath = GetXmlCommentsPath();
services.AddMvc();
services.AddSwaggerGen();
services.ConfigureSwaggerGen(options =>
{
options.SingleApiVersion(new Info
{
Version = \"v1\",
Title = \"SepidAria API\",
Description = \"My First ASP.NET Core Web API\",
TermsOfService = \"None\",
Contact = new Contact() { Name = \"Talking Dotnet\", Email = \"Mohsen Derambakht\",
Url = \"www.sepidaria.com\" }
});
options.IncludeXmlComments(xmlPath);
});
}

به سراغ controller متبوع خویش بروید و برای یکی متدها خویش توضیحی مانند کد ذیل قرار دهید :

1
2
3
4
5
6
7
8
9
10
// DELETE api/values/5
///

/// Delete API Value
///
/// This API will delete the values.
///
[HttpDelete(\"{id}\")]
public void Delete(int id)
{
}

دوباره پروژه را اجرا کنید. اینجانب در پروژه خویش دو کنترلر اضافه نمودم و برای متدهای کنترلر Product خویش توضیحاتی را قرار دادم.
در تصویر پایین یک راهنمای حدودا بی نقص را مشاهده می فرمائید.